前言

前面几个博客向大家介绍了查询构造器的原理与源码，然而查询构造器更多是为 Eloquent Model 服务的，我们对数据库操作更加方便的是使用 Eloquent Model。 本篇文章将会大家介绍 Model 的一些特性原理。

Eloquent Model 修改器

当我们在 Eloquent 模型实例中设置某些属性值的时候，修改器允许对 Eloquent 属性值进行格式化。如果对修改器不熟悉，请参考官方文档：Eloquent： 修改器

下面先看看修改器的原理：

  1. public function offsetSet($offset, $value)
  2. {
  3.     $this->setAttribute($offset, $value);
  4. }
  6. public function setAttribute($key, $value)
  7. {
  8.     if ($this->hasSetMutator($key)) {
  9.         $method = 'set'.Str::studly($key).'Attribute';
  11.         return $this->{$method}($value);
  12.     }
  14.     elseif ($value && $this->isDateAttribute($key)) {
  15.         $value = $this->fromDateTime($value);
  16.     }
  18.     if ($this->isJsonCastable($key) && ! is_null($value)) {
  19.         $value = $this->castAttributeAsJson($key, $value);
  20.     }
  22.     if (Str::contains($key, '->')) {
  23.         return $this->fillJsonAttribute($key, $value);
  24.     }
  26.     $this->attributes[$key] = $value;
  28.     return $this;
  29. }

自定义修改器

当我们为 model 的成员变量赋值的时候，就会调用 offsetSet 函数，进而运行 setAttribute 函数，在这个函数中第一个检查的就是是否存在预处理函数：

  1. public function hasSetMutator($key)
  2. {
  3.     return method_exists($this, 'set'.Str::studly($key).'Attribute');
  4. }

如果存在该函数，就会直接调用自定义修改器。

日期转换器

接着如果没有自定义修改器的话，还会检查当前更新的成员变量是否是日期属性：

  1. protected function isDateAttribute($key)
  2. {
  3.     return in_array($key, $this->getDates()) ||
  4.                                 $this->isDateCastable($key);
  5. }
  7. public function getDates()
  8. {
  9.     $defaults = [static::CREATED_AT, static::UPDATED_AT];
  11.     return $this->usesTimestamps()
  12.                 ? array_unique(array_merge($this->dates, $defaults))
  13.                 : $this->dates;
  14. }
  16. protected function isDateCastable($key)
  17. {
  18.     return $this->hasCast($key, ['date', 'datetime']);
  19. }

字段的时间属性有两种设置方法，一种是设置 $dates 属性：

  1. protected $dates = ['date_attr'];

还有一种方法是设置 cast 数组：

  1. protected $casts = ['date_attr' => 'date'];

只要是时间属性的字段，无论是什么类型的值，laravel 都会自动将其转化为数据库的时间格式。数据库的时间格式设置是 dateFormat 成员变量，不设置的时候，默认的时间格式为 `Y-m-d H:i:s’:

  1. protected $dateFormat = ['U'];
  3. protected $dateFormat = ['Y-m-d H:i:s'];

当数据库对应的字段是时间类型时，为其赋值就可以非常灵活。我们可以赋值 Carbon 类型、DateTime 类型、数字类型、字符串等等：

  1. public function fromDateTime($value)
  2. {
  3.     return is_null($value) ? $value : $this->asDateTime($value)->format(
  4.         $this->getDateFormat()
  5.     );
  6. }
  8. protected function asDateTime($value)
  9. {
  10.     if ($value instanceof Carbon) {
  11.         return $value;
  12.     }
  14.     if ($value instanceof DateTimeInterface) {
  15.         return new Carbon(
  16.             $value->format('Y-m-d H:i:s.u'), $value->getTimezone()
  17.         );
  18.     }
  20.     if (is_numeric($value)) {
  21.         return Carbon::createFromTimestamp($value);
  22.     }
  24.     if ($this->isStandardDateFormat($value)) {
  25.         return Carbon::createFromFormat('Y-m-d', $value)->startOfDay();
  26.     }
  28.     return Carbon::createFromFormat(
  29.         $this->getDateFormat(), $value
  30.     );
  31. }

json 转换器

接下来，如果该变量被设置为 array、json 等属性，那么其将会转化为 json 类型。

  1. protected function isJsonCastable($key)
  2. {
  3.     return $this->hasCast($key, ['array', 'json', 'object', 'collection']);
  4. }
  6. protected function asJson($value)
  7. {
  8.     return json_encode($value);
  9. }

Eloquent Model 访问器

相比较修改器来说，访问器的适用情景会更加多。例如，我们经常把一些关于类型的字段设置为 1、2、3 等等，例如用户数据表中用户性别字段，1 代表男，2 代表女，很多时候我们取出这些值之后必然要经过转换，然后再显示出来。这时候就需要定义访问器。

访问器的源码：

  1. public function getAttribute($key)
  2. {
  3.     if (! $key) {
  4.         return;
  5.     }
  7.     if (array_key_exists($key, $this->attributes) ||
  8.         $this->hasGetMutator($key)) {
  9.         return $this->getAttributeValue($key);
  10.     }
  12.     if (method_exists(self::class, $key)) {
  13.         return;
  14.     }
  16.     return $this->getRelationValue($key);
  17. }

可以看到，当我们访问数据库对象的成员变量的时候，大致可以分为两类：属性值与关系对象。关系对象我们以后再详细来说，本文中先说关于属性的访问。

  1. public function getAttributeValue($key)
  2. {
  3.     $value = $this->getAttributeFromArray($key);
  5.     if ($this->hasGetMutator($key)) {
  6.         return $this->mutateAttribute($key, $value);
  7.     }
  9.     if ($this->hasCast($key)) {
  10.         return $this->castAttribute($key, $value);
  11.     }
  13.     if (in_array($key, $this->getDates()) &&
  14.         ! is_null($value)) {
  15.         return $this->asDateTime($value);
  16.     }
  18.     return $value;
  19. }

与修改器类似，访问器也由三部分构成：自定义访问器、日期访问器、类型访问器。

获取原始值

访问器的第一步就是从成员变量 attributes 中获取原始的字段值，一般指的是存在数据库的值。有的时候，我们要取的属性并不在 attributes 中，这时候就会返回 null。

  1. protected function getAttributeFromArray($key)
  2. {
  3.     if (isset($this->attributes[$key])) {
  4.         return $this->attributes[$key];
  5.     }
  6. }

自定义访问器

如果定义了访问器，那么就会调用访问器，获取返回值：

  1. public function hasGetMutator($key)
  2. {
  3.     return method_exists($this, 'get'.Str::studly($key).'Attribute');
  4. }
  6. protected function mutateAttribute($key, $value)
  7. {
  8.     return $this->{'get'.Str::studly($key).'Attribute'}($value);
  9. }

类型转换

若我们在成员变量 $casts 数组中为属性定义了类型转换，那么就要进行类型转换：

  1. public function hasCast($key, $types = null)
  2. {
  3.     if (array_key_exists($key, $this->getCasts())) {
  4.         return $types ? in_array($this->getCastType($key), (array) $types, true) : true;
  5.     }
  7.     return false;
  8. }
  10. protected function castAttribute($key, $value)
  11. {
  12.     if (is_null($value)) {
  13.         return $value;
  14.     }
  16.     switch ($this->getCastType($key)) {
  17.         case 'int':
  18.         case 'integer':
  19.             return (int) $value;
  20.         case 'real':
  21.         case 'float':
  22.         case 'double':
  23.             return (float) $value;
  24.         case 'string':
  25.             return (string) $value;
  26.         case 'bool':
  27.         case 'boolean':
  28.             return (bool) $value;
  29.         case 'object':
  30.             return $this->fromJson($value, true);
  31.         case 'array':
  32.         case 'json':
  33.             return $this->fromJson($value);
  34.         case 'collection':
  35.             return new BaseCollection($this->fromJson($value));
  36.         case 'date':
  37.             return $this->asDate($value);
  38.         case 'datetime':
  39.             return $this->asDateTime($value);
  40.         case 'timestamp':
  41.             return $this->asTimestamp($value);
  42.         default:
  43.             return $value;
  44.     }
  45. }

日期转换

若当前属性是 CREATED_AT、UPDATED_AT 或者被存入成员变量 dates 中，那么就要进行日期转换。日期转换函数 asDateTime 可以查看上一节中的内容。

Eloquent Model 数组转化

在使用数据库对象中，我们经常使用 toArray 函数，它可以将从数据库中取出的所有属性和关系模型转化为数组：

  1. public function toArray()
  2. {
  3.     return array_merge($this->attributesToArray(), $this->relationsToArray());
  4. }

本文中只介绍属性转化为数组的部分：

  1. public function attributesToArray()
  2. {
  3.     $attributes = $this->addDateAttributesToArray(
  4.         $attributes = $this->getArrayableAttributes()
  5.     );
  7.     $attributes = $this->addMutatedAttributesToArray(
  8.         $attributes, $mutatedAttributes = $this->getMutatedAttributes()
  9.     );
  11.     $attributes = $this->addCastAttributesToArray(
  12.         $attributes, $mutatedAttributes
  13.     );
  15.     foreach ($this->getArrayableAppends() as $key) {
  16.         $attributes[$key] = $this->mutateAttributeForArray($key, null);
  17.     }
  19.     return $attributes;
  20. }

与访问器与修改器类似，需要转为数组的元素有日期类型、自定义访问器、类型转换，我们接下来一个个看：

getArrayableAttributes 原始值获取

首先我们要从成员变量 attributes 数组中获取原始值：

  1. protected function getArrayableAttributes()
  2. {
  3.     return $this->getArrayableItems($this->attributes);
  4. }
  6. protected function getArrayableItems(array $values)
  7. {
  8.     if (count($this->getVisible()) > 0) {
  9.         $values = array_intersect_key($values, array_flip($this->getVisible()));
  10.     }
  12.     if (count($this->getHidden()) > 0) {
  13.         $values = array_diff_key($values, array_flip($this->getHidden()));
  14.     }
  16.     return $values;
  17. }

我们还可以为数据库对象设置可见元素 $visible 与隐藏元素 $hidden，这两个变量会控制 toArray 可转化的元素属性。

日期转换

  1. protected function addDateAttributesToArray(array $attributes)
  2. {
  3.     foreach ($this->getDates() as $key) {
  4.         if (! isset($attributes[$key])) {
  5.             continue;
  6.         }
  8.         $attributes[$key] = $this->serializeDate(
  9.             $this->asDateTime($attributes[$key])
  10.         );
  11.     }
  13.     return $attributes;
  14. }
  16. protected function serializeDate(DateTimeInterface $date)
  17. {
  18.     return $date->format($this->getDateFormat());
  19. }

自定义访问器转换

定义了自定义访问器的属性，会调用访问器函数来覆盖原有的属性值，首先我们需要获取所有的自定义访问器变量：

  1. public function getMutatedAttributes()
  2. {
  3.     $class = static::class;
  5.     if (! isset(static::$mutatorCache[$class])) {
  6.         static::cacheMutatedAttributes($class);
  7.     }
  9.     return static::$mutatorCache[$class];
  10. }
  12. public static function cacheMutatedAttributes($class)
  13. {
  14.     static::$mutatorCache[$class] = collect(static::getMutatorMethods($class))->map(function ($match) {
  15.         return lcfirst(static::$snakeAttributes ? Str::snake($match) : $match);
  16.     })->all();
  17. }
  19. protected static function getMutatorMethods($class)
  20. {
  21.     preg_match_all('/(?<=^|;)get([^;]+?)Attribute(;|$)/', implode(';', get_class_methods($class)), $matches);
  23.     return $matches[1];
  24. }

可以看到，函数用 get_class_methods 获取类内所有的函数，并筛选出符合 get...Attribute 的函数，获得自定义的访问器变量，并缓存到 mutatorCache 中。

接着将会利用自定义访问器变量替换原始值：

  1. protected function addMutatedAttributesToArray(array $attributes, array $mutatedAttributes)
  2. {
  3.     foreach ($mutatedAttributes as $key) {
  4.         if (! array_key_exists($key, $attributes)) {
  5.             continue;
  6.         }
  8.         $attributes[$key] = $this->mutateAttributeForArray(
  9.             $key, $attributes[$key]
  10.         );
  11.     }
  13.     return $attributes;
  14. }
  16. protected function mutateAttributeForArray($key, $value)
  17. {
  18.     $value = $this->mutateAttribute($key, $value);
  20.     return $value instanceof Arrayable ? $value->toArray() : $value;
  21. }

cast 类型转换

被定义在 cast 数组中的变量也要进行数组转换，调用的方法和访问器相同，也是 castAttribute，如果是时间类型，还要按照时间格式来转换：

  1. protected function addCastAttributesToArray(array $attributes, array $mutatedAttributes)
  2. {
  3.     foreach ($this->getCasts() as $key => $value) {
  4.         if (! array_key_exists($key, $attributes) || in_array($key, $mutatedAttributes)) {
  5.             continue;
  6.         }
  8.         $attributes[$key] = $this->castAttribute(
  9.             $key, $attributes[$key]
  10.         );
  12.         if ($attributes[$key] &&
  13.             ($value === 'date' || $value === 'datetime')) {
  14.             $attributes[$key] = $this->serializeDate($attributes[$key]);
  15.         }
  16.     }
  18.     return $attributes;
  19. }

appends 额外属性添加

toArray() 还会将我们定义在 appends 变量中的属性一起进行数组转换，但是注意被放入 appends 成员变量数组中的属性需要有自定义访问器函数：

  1. protected function getArrayableAppends()
  2. {
  3.     if (! count($this->appends)) {
  4.         return [];
  5.     }
  7.     return $this->getArrayableItems(
  8.         array_combine($this->appends, $this->appends)
  9.     );
  10. }

查询作用域

查询作用域分为全局作用域与本地作用域。全局作用域不需要手动调用，由程序在每次的查询中自动加载，本地作用域需要在查询的时候进行手动调用。官方文档：查询作用域

全局作用域

一般全局作用域需要定义一个实现 Illuminate\Database\Eloquent\Scope 接口的类，该接口要求你实现一个方法：apply。需要的话可以在 apply 方法中添加 where 条件到查询。

要将全局作用域分配给模型，需要重写给定模型的 boot 方法并使用 addGlobalScope 方法。

另外，我们还可以向 addGlobalScope 中添加匿名函数实现匿名全局作用域。

我们先看看源码：

  1. public static function addGlobalScope($scope, Closure $implementation = null)
  2. {
  3.     if (is_string($scope) && ! is_null($implementation)) {
  4.         return static::$globalScopes[static::class][$scope] = $implementation;
  5.     } elseif ($scope instanceof Closure) {
  6.         return static::$globalScopes[static::class][spl_object_hash($scope)] = $scope;
  7.     } elseif ($scope instanceof Scope) {
  8.         return static::$globalScopes[static::class][get_class($scope)] = $scope;
  9.     }
  11.     throw new InvalidArgumentException('Global scope must be an instance of Closure or Scope.');
  12. }

可以看到，全局作用域使用的是全局的静态变量 globalScopes，该变量保存着所有数据库对象的全局作用域。

Eloquent\Model 类并不负责查询功能，相关功能由 Eloquent\Builder 负责，因此每次查询都会间接调用 Eloquent\Builder 类。

  1. public function __call($method, $parameters)
  2. {
  3.     if (in_array($method, ['increment', 'decrement'])) {
  4.         return $this->$method(...$parameters);
  5.     }
  7.     try {
  8.         return $this->newQuery()->$method(...$parameters);
  9.     } catch (BadMethodCallException $e) {
  10.         throw new BadMethodCallException(
  11.             sprintf('Call to undefined method %s::%s()', get_class($this), $method)
  12.         );
  13.     }
  14. }

创建新的 Eloquent\Builder 类需要 newQuery 函数：

  1. public function newQuery()
  2. {
  3.     $builder = $this->newQueryWithoutScopes();
  5.     foreach ($this->getGlobalScopes() as $identifier => $scope) {
  6.         $builder->withGlobalScope($identifier, $scope);
  7.     }
  9.     return $builder;
  10. }
  12. public function getGlobalScopes()
  13. {
  14.     return Arr::get(static::$globalScopes, static::class, []);
  15. }
  17. public function withGlobalScope($identifier, $scope)
  18. {
  19.     $this->scopes[$identifier] = $scope;
  21.     if (method_exists($scope, 'extend')) {
  22.         $scope->extend($this);
  23.     }
  25.     return $this;
  26. }

newQuery 函数为 Eloquent\builder 加载全局作用域，这样静态变量 globalScopes 的值就会被赋到 Eloquent\builder 的 scopes 成员变量中。

当我们使用 get() 函数获取数据库数据的时候，也需要借助魔术方法调用 Illuminate\Database\Eloquent\Builder 类的 get 函数：

  1. public function get($columns = ['*'])
  2. {
  3.     $builder = $this->applyScopes();
  5.     if (count($models = $builder->getModels($columns)) > 0) {
  6.         $models = $builder->eagerLoadRelations($models);
  7.     }
  9.     return $builder->getModel()->newCollection($models);
  10. }

调用 applyScopes 函数加载所有的全局作用域：

  1. public function applyScopes()
  2. {
  3.     if (! $this->scopes) {
  4.         return $this;
  5.     }
  7.     $builder = clone $this;
  9.     foreach ($this->scopes as $identifier => $scope) {
  10.         if (! isset($builder->scopes[$identifier])) {
  11.             continue;
  12.         }
  14.         $builder->callScope(function (Builder $builder) use ($scope) {
  15.             if ($scope instanceof Closure) {
  16.                 $scope($builder);
  17.             }
  19.             if ($scope instanceof Scope) {
  20.                 $scope->apply($builder, $this->getModel());
  21.             }
  22.         });
  23.     }
  25.     return $builder;
  26. }

可以看到，builder 查询类会通过 callScope 加载全局作用域的查询条件。

  1. protected function callScope(callable $scope, $parameters = [])
  2. {
  3.     array_unshift($parameters, $this);
  5.     $query = $this->getQuery();
  7.     $originalWhereCount = is_null($query->wheres)
  8.                 ? 0 : count($query->wheres);
  10.     $result = $scope(...array_values($parameters)) ?? $this;
  12.     if (count((array) $query->wheres) > $originalWhereCount) {
  13.         $this->addNewWheresWithinGroup($query, $originalWhereCount);
  14.     }
  16.     return $result;
  17. }

callScope 函数首先会获取更加底层的 Query\builder，更新 query\bulid 的 where 条件。

addNewWheresWithinGroup 这个函数很重要，它为 Query\builder 提供 nest 类型的 where 条件：

  1. protected function addNewWheresWithinGroup(QueryBuilder $query, $originalWhereCount)
  2. {
  3.     $allWheres = $query->wheres;
  5.     $query->wheres = [];
  7.     $this->groupWhereSliceForScope(
  8.         $query, array_slice($allWheres, 0, $originalWhereCount)
  9.     );
  11.     $this->groupWhereSliceForScope(
  12.         $query, array_slice($allWheres, $originalWhereCount)
  13.     );
  14. }
  16. protected function groupWhereSliceForScope(QueryBuilder $query, $whereSlice)
  17. {
  18.     $whereBooleans = collect($whereSlice)->pluck('boolean');
  20.     if ($whereBooleans->contains('or')) {
  21.         $query->wheres[] = $this->createNestedWhere(
  22.             $whereSlice, $whereBooleans->first()
  23.         );
  24.     } else {
  25.         $query->wheres = array_merge($query->wheres, $whereSlice);
  26.     }
  27. }
  29. protected function createNestedWhere($whereSlice, $boolean = 'and')
  30. {
  31.     $whereGroup = $this->getQuery()->forNestedWhere();
  33.     $whereGroup->wheres = $whereSlice;
  35.     return ['type' => 'Nested', 'query' => $whereGroup, 'boolean' => $boolean];
  36. }

当我们在查询作用域中，所有的查询条件连接符都是 and 的时候，可以直接合并到 where 中。

如果我们在查询作用域中或者原查询条件写下了 orWhere、orWhereColumn 等等连接符为 or 的查询条件，那么就会利用 createNestedWhere 函数创建 nest 类型的 where 条件。这个 where 条件会包含查询作用域的所有查询条件，或者原查询的所有查询条件。

本地作用域

全局作用域会自定加载到所有的查询条件当中，laravel 中还有本地作用域，只有在查询时调用才会生效。

本地作用域是由魔术方法 __call 实现的：

  1. public function __call($method, $parameters)
  2. {
  3.     ...
  5.     if (method_exists($this->model, $scope = 'scope'.ucfirst($method))) {
  6.         return $this->callScope([$this->model, $scope], $parameters);
  7.     }
  9.     if (in_array($method, $this->passthru)) {
  10.         return $this->toBase()->{$method}(...$parameters);
  11.     }
  13.     $this->query->{$method}(...$parameters);
  15.     return $this;
  16. }

批量调用本地作用域

laravel 还提供一个方法可以一次性调用多个本地作用域：

  1. $scopes = [
  2.     'published',
  3.     'category' => 'Laravel',
  4.     'framework' => ['Laravel', '5.3'],
  5. ];
  7. (new EloquentModelStub)->scopes($scopes);

上面的写法会调用三个本地作用域，它们的参数是 $scopes 的值。

  1. public function scopes(array $scopes)
  2. {
  3.     $builder = $this;
  5.     foreach ($scopes as $scope => $parameters) {
  6.         if (is_int($scope)) {
  7.             list($scope, $parameters) = [$parameters, []];
  8.         }
  10.         $builder = $builder->callScope(
  11.             [$this->model, 'scope'.ucfirst($scope)],
  12.             (array) $parameters
  13.         );
  14.     }
  16.     return $builder;
  17. }

fill 批量赋值

Eloquent Model 默认只能一个一个的设置数据库对象的属性，这是为了保护数据库。但是有的时候，字段过多会造成代码很繁琐。因此，laravel 提供属性批量赋值的功能，fill 函数，相关的官方文档：批量赋值

fill 函数

  1. public function fill(array $attributes)
  2. {
  3.     $totallyGuarded = $this->totallyGuarded();
  5.     foreach ($this->fillableFromArray($attributes) as $key => $value) {
  6.         $key = $this->removeTableFromKey($key);
  8.         if ($this->isFillable($key)) {
  9.             $this->setAttribute($key, $value);
  10.         } elseif ($totallyGuarded) {
  11.             throw new MassAssignmentException($key);
  12.         }
  13.     }
  15.     return $this;
  16. }

fill 函数会从参数 attributes 中选取可以批量赋值的属性。所谓的可以批量赋值的属性，是指被 fillable 或 guarded 成员变量设置的参数。被放入 fillable 的属性允许批量赋值的属性，被放入 guarded 的属性禁止批量赋值。

获取可批量赋值的属性：

  1. protected function fillableFromArray(array $attributes)
  2. {
  3.     if (count($this->getFillable()) > 0 && ! static::$unguarded) {
  4.         return array_intersect_key($attributes, array_flip($this->getFillable()));
  5.     }
  7.     return $attributes;
  8. }
  10. public function getFillable()
  11. {
  12.     return $this->fillable;
  13. }

可以看到，若想要实现批量赋值，需要将属性设置在 fillable 成员数组中。

在 laravel 中，有一种数据库对象关系是 morph，也就是 多态 关系，这种关系也会调用 fill 函数，这个时候传入的参数 attributes 会带有数据库前缀。接下来，就要调用 removeTableFromKey 函数来去除数据库前缀：

  1. protected function removeTableFromKey($key)
  2. {
  3.     return Str::contains($key, '.') ? last(explode('.', $key)) : $key;
  4. }

下一步，还要进一步验证属性的 fillable：

  1. public function isFillable($key)
  2. {
  3.     if (static::$unguarded) {
  4.         return true;
  5.     }
  7.     if (in_array($key, $this->getFillable())) {
  8.         return true;
  9.     }
  11.     if ($this->isGuarded($key)) {
  12.         return false;
  13.     }
  15.     return empty($this->getFillable()) &&
  16.         ! Str::startsWith($key, '_');
  17. }

如果当前 unguarded 开启，也就是不会保护任何属性，那么直接返回 true。如果当前属性在 fillable 中，也会返回 true。如果当前属性在 guarded 中，返回 false。最后，如果 fillable 是空数组，也会返回 true。

forceFill

如果不想受 fillable 或者 guarded 等的影响，还可以使用 forceFill 强制来批量赋值。

  1. public function forceFill(array $attributes)
  2. {
  3.     return static::unguarded(function () use ($attributes) {
  4.         return $this->fill($attributes);
  5.     });
  6. }
  8. public static function unguarded(callable $callback)
  9. {
  10.     if (static::$unguarded) {
  11.         return $callback();
  12.     }
  14.     static::unguard();
  16.     try {
  17.         return $callback();
  18.     } finally {
  19.         static::reguard();
  20.     }
  21. }